The CreateWindow function creates an overlapped, pop-up, or child window. It specifies the window class, window title, window style, and (optionally) the initial position and size of the window. The function also specifies the window's parent or owner, if any, and the window's menu.
To use extended window styles in addition to the styles supported by CreateWindow, use the
programming - windows - CreateWindowEx function.
Syntax HWND CreateWindow(
LPCTSTR lpClassName,
LPCTSTR lpWindowName,
DWORD dwStyle,
int x,
int y,
int nWidth,
int nHeight,
HWND hWndParent,
HMENU hMenu,
HINSTANCE hInstance,
LPVOID lpParam
);
Parameters
- lpClassName Pointer to a null-terminated string or a class atom created
by a previous call to the [RegisterClass] or [RegisterClassEx] function.
The atom must be in the low-order word of lpClassName; the high-order
word must be zero. If lpClassName is a string, it specifies the window
class name. The class name can be any name registered with
RegisterClass or RegisterClassEx, provided that the module that
registers the class is also the module that creates the window. The
class name can also be any of the predefined system class names. For a
list of system class names, see the Remarks section.
- lpWindowName Pointer to a null-terminated string that specifies the
window name. If the window style specifies a title bar, the window
title pointed to by lpWindowName is displayed in the title bar. When
using CreateWindow to create controls, such as buttons, check boxes,
and static controls, use lpWindowName to specify the text of the
control. When creating a static control with the SS_ICON style, use
lpWindowName to specify the icon name or identifier. To specify an
identifier, use the syntax "#num".
- dwStyle Specifies the style of the window being created. This
parameter can be a combination of window styles, plus the control
styles indicated in the Remarks section.
- x Specifies the initial horizontal position of the window. For
an overlapped or pop-up window, the x parameter is the initial
x-coordinate of the window's upper-left corner, in screen coordinates.
For a child window, x is the x-coordinate of the upper-left corner of
the window relative to the upper-left corner of the parent window's
client area. If this parameter is set to CW_USEDEFAULT, the system
selects the default position for the window's upper-left corner and
ignores the y parameter. CW_USEDEFAULT is valid only for overlapped
windows; if it is specified for a pop-up or child window, the x and y
parameters are set to zero.
- y Specifies the initial vertical position of the window. For
an overlapped or pop-up window, the y parameter is the initial
y-coordinate of the window's upper-left corner, in screen coordinates.
For a child window, y is the initial y-coordinate of the upper-left
corner of the child window relative to the upper-left corner of the
parent window's client area. For a list box, y is the initial
y-coordinate of the upper-left corner of the list box's client area
relative to the upper-left corner of the parent window's client area.
If an overlapped window is created with the WS_VISIBLE style bit set
and the x parameter is set to CW_USEDEFAULT, then the y parameter
determines how the window is shown. If the y parameter is
CW_USEDEFAULT, then the window manager calls ShowWindow with the
SW_SHOW flag after the window has been created. If the y parameter is
some other value, then the window manager calls ShowWindow with that
value as the nCmdShow parameter.
- nWidth Specifies the width, in device units, of the window. For
overlapped windows, nWidth is either the window's width, in screen
coordinates, or CW_USEDEFAULT. If nWidth is CW_USEDEFAULT, the system
selects a default width and height for the window; the default width
extends from the initial x-coordinate to the right edge of the screen,
and the default height extends from the initial y-coordinate to the top
of the icon area. CW_USEDEFAULT is valid only for overlapped windows;
if CW_USEDEFAULT is specified for a pop-up or child window, nWidth and
nHeight are set to zero.
- nHeight Specifies the height, in device units, of the window. For
overlapped windows, nHeight is the window's height, in screen
coordinates. If nWidth is set to CW_USEDEFAULT, the system ignores
nHeight.
- hWndParent Handle to the parent or owner window of the window being
created. To create a child window or an owned window, supply a valid
window handle. This parameter is optional for pop-up windows.
Windows 2000/XP: To create a [message-only window], supply HWND_MESSAGE or a handle to an existing message-only window.
- hMenu Handle to a menu, or specifies a child-window identifier depending on the window style. For an overlapped or pop-up window, hMenu identifies the menu to be used with the window; it can be NULL if the class menu is to be used. For a child window, hMenu specifies the child-window identifier, an integer value used by a dialog box control to notify its parent about events. The application determines the child-window identifier; it must be unique for all child windows with the same parent window.
- hInstance Handle to the instance of the module to be associated with the window.
- lpParam Pointer to a value to be passed to the window through the [CREATESTRUCT] structure (lpCreateParams member) pointed to by the lParam param of the [WM_CREATE] message. This message is sent to the created window by this function before it returns.
If an application calls CreateWindow to create a multiple-document interface (MDI) client window, lpParam should point to a [CLIENTCREATESTRUCT] structure. If an MDI client window calls CreateWindow to create an MDI child window, lpParam should point to a [MDICREATESTRUCT] structure. lpParam may be NULL if no additional data is needed.
Return Value
If the function succeeds, the return value is a handle to the new window.
If the function fails, the return value is NULL. To get extended error information, call GetLastError.
This function typically fails for one of the following reasons:
- an invalid parameter value
- the system class was registered by a different module
- The WH_CBT hook is installed and returns a failure code
- if one of the controls in the dialog template is not registered, or its window window procedure fails [WM_CREATE] or [WM_NCCREATE]
Remarks
Before returning, CreateWindow sends a [WM_CREATE] message to the window
procedure. For overlapped, pop-up, and child windows, CreateWindow sends
programming - windows - WM_CREATE,
programming:windows:WM_GETMINMAXINFO, and
programming:windows:WM_NCCREATE messages to the
window. The lParam parameter of the
programming - windows - WM_CREATE message contains a
pointer to a
programming:windows:CREATESTRUCT structure. If the WS_VISIBLE style is
specified, CreateWindow sends the window all the messages required to
activate and show the window.
If the created window is a child window, its default position is at the
bottom of the Z-order. If the created window is a top-level window, its
default position is at the top of the Z-order (but beneath all topmost
windows unless the created window is itself topmost).
For information on controlling whether the Taskbar displays a button for
the created window, see Managing Taskbar Buttons.
The following predefined system classes can be specified in the
lpClassName parameter. Note the corresponding control styles you can use
in the dwStyle parameter.
System class | Meaning |
---|
BUTTON | Designates a small rectangular child window that represents a button the user can click to turn it on or off. Button controls can be used alone or in groups, and they can either be labeled or appear without text. Button controls typically change appearance when the user clicks them. For more information, see [Buttons].
- For a table of the button styles you can specify in the dwStyle
parameter, see [Button Styles].
|
COMBOBOX | Designates a control consisting of a list box and a selection field similar to an edit control. When using this style, an application should either display the list box at all times or enable a drop-down list box. If the list box is visible, typing characters into the selection field highlights the first list box entry that matches the characters typed. Conversely, selecting an item in the list box displays the selected text in the selection field.
For more information, see [Combo Boxes].
For a table of the combo box styles you can specify in the dwStyle parameter, see [Combo Box Styles].
|
EDIT | Designates a rectangular child window into which the user can type
text from the keyboard. The user selects the control and gives it the
keyboard focus by clicking it or moving to it by pressing the TAB key.
The user can type text when the edit control displays a flashing caret;
use the mouse to move the cursor, select characters to be replaced, or
position the cursor for inserting characters; or use the BACKSPACE key
to delete characters. For more information, see [Edit Controls].
- For a table of the edit control styles you can specify in the dwStyle
parameter, see [Edit Control Styles].
|
LISTBOX | Designates a list of character strings. Specify this control whenever an application must present a list of names, such as file names, from which the user can choose. The user can select a string by clicking it. A selected string is highlighted, and a notification message is passed to the parent window. For more information, see [List Boxes].
- For a table of the list box styles you can specify in the dwStyle parameter, see [List Box Styles].
|
MDICLIENT | Designates an MDI client window. This window receives
messages that control the MDI application's child windows. The
recommended style bits are WS_CLIPCHILDREN and WS_CHILD. Specify the
WS_HSCROLL and WS_VSCROLL styles to create an MDI client window that
allows the user to scroll MDI child windows into view.
- For more information, see Multiple Document Interface.
|
RichEdit | Designates a Microsoft Rich Edit 1.0 control. This window lets the user view and edit text with character and paragraph formatting, and can include embedded Component Object Model (COM) objects. For more information, see [Rich Edit Controls].
For a table of the rich edit control styles you can specify in the dwStyle parameter, see [Rich Edit Control Styles].
|
RICHEDIT_CLASS | Designates a Rich Edit 2.0 control. This controls let the user view and edit text with character and paragraph formatting, and can include embedded COM objects. For more information, see [Rich Edit Controls].
- For a table of the rich edit control styles you can specify in the
dwStyle parameter, see [Rich Edit Control Styles].
|
SCROLLBAR | Designates a rectangle that contains a scroll box and has
direction arrows at both ends. The scroll bar sends a notification
message to its parent window whenever the user clicks the control. The
parent window is responsible for updating the position of the scroll
box, if necessary. For more information, see [Scroll Bars].
- For a table of the scroll bar control styles you can specify in the dwStyle parameter, see [Scroll Bar Control Styles].
|
STATIC | Designates a simple text field, box, or rectangle used to label,
box, or separate other controls. Static controls take no input and
provide no output. For more information, see [Static Controls].
- For a table of the static control styles you can specify in the dwStyle
parameter, see [Static Control Styles].
|
- Windows 95/98/Me:The system can support a maximum of 16,364 window handles.
- Windows 95/98/Me: CreateWindowW is supported by the Microsoft Layer for
Unicode (MSLU). To use this, you must add certain files to your
application, as outlined in Microsoft Layer for Unicode on Windows
95/98/Me Systems .
Note If you specify Microsoft Windows version 4.x or later when linking your application, its windows cannot have caption buttons unless they also have window menus. This is not a requirement if you specify Windows version 3.x when linking your application.
Function Information
- Minimum DLL Version user32.dll
- Header Declared in Winuser.h, include Windows.h
- Import library User32.lib
- Minimum operating systems Windows 95, Windows NT 3.1
- Unicode Implemented as ANSI and Unicode versions.